package org.javanum.number;

/**
 * <p>Defines common operations for the Complex Field.</p>
 * 
 * <p>This interface defines the <i>Cartesian Form</i> of the Complex field.
 *  Thus,elements which implement this interface are of the form 
 *  {@code a+ib}, where{@code a} and {@code b} are real numbers and 
 *  {@code i} is defined as the number such that {@code i^2=-1}.</p>
 * 
 * <p>The Complex Field is also defined in Polar Coordinates. For more 
 * information, see {@link PolarComplexField}.</p>
 *  
 * 
 * Author: Scott Fines
 * Date: Oct 23, 2009
 * @version 1.0
 *
 * @param <R> the return type of the Real SubField in this implementation.
 * @param <V> the return type of this implementation.
 * @param <T> the return type of how the data is stored. 
 */
public interface CartesianComplexField
        <R extends RealField<R,T>,
		 V extends CartesianComplexField<R,V,T>,
		 T extends Number> extends ComplexField<R,V,T> {
	
	/**
	 * <p>Returns the real part of {@code this}. If {@code this=a+ib}, then 
	 * this method returns {@code a}.</p>
	 * 
	 * @return the real part of {@code this}, as an implementation of the 
	 * {@link RealField} interface.
	 */
	public R realPart();
	
	/**
	 * <p>Returns the imaginary part of {@code this}. If {@code this=a+ib}, 
	 * then this method returns {@code b}.</p>
	 * 
	 * @return the imaginary part of {@code this}, as an implementation of 
	 * the {@link RealField} interface.
	 */
	public R imaginaryPart();
	
	/**
     * {@inheritDoc ComplexField.modulus()}
	 * <p> In the case of the cartesian form, if the complex
     * number is {@code a+ib}, then the modulus of that
	 * number is defined as the result of the computation 
	 * {@code Math.sqrt(Math.pow(a,2)+Math.pow(b,2))}.</p>
	 *  
	 * @return the modulus of {@code this}.
	 */
	public T modulus();
	
	/**
     * {@inheritDoc ComplexField.conjugate()}
     * 
	 * <p>The <i>complex conjugate</i> of a complex number {@code z=a+ib} 
	 * is defined as the complex number {@code w=a-ib}.The result of 
	 * multiplying z*w is then Math.pow(a,2)+Math.pow(b,2), or the 
	 * square of the modulus of {@code z}.</p>
	 * 
	 * @return the complex conjugate of {@code this}.
	 */
	public V conjugate();
	
	/**
	 * @param <K> the return type as an implementation of 
	 * {@link PolarComplexField}
	 * 
	 * @return {@code this} in polar form--that is, as an implementation of 
	 * {@link PolarComplexField}
	 */
	public <K extends PolarComplexField<R,K,T>> K polarForm();
	
}
